Developer --> Technical Publications
PATHHardware Documentation > USB Devices > Mac OS USB DDK API Reference


USB Transaction Functions

There are four transaction types supported by the USL, control, interrupt, bulk, or isochronous. When making isochronous calls, you set the pbVersion field in the USBPB parameter block to kUSBIsocPBVersion, and use the isochronous variant of the USBPB parameter block, described in The Isochronous Version Of The USBPB .

USBIntRead

The USBIntRead function queues an interrupt transaction on the specified pipe. The device is periodically polled and the transaction completes when the device returns some data. This is a read operation only. Version 1.0 of the USB specification does not define an interrupt write function.

OSStatus USBIntRead(USBPB *pb);

Required fields in the USBPB parameter block for the USBIntRead function are

--> pbLength
Length of parameter block
--> pbVersion
Parameter block version number
--> usbCompletion
The completion routine
--> usbRefcon
General-purpose value passed back to the completion routine
--> usbReference
The pipe reference returned by the USBFindNextPipe function
--> usbReqCount
Specifies the size of the data to transfer. If this is set to 0, anything but a zero length packet causes an error
--> usbBuffer
Points to a buffer to which the incoming data is transferred
<-- usbActCount
Specifies the actual amount of data transferred on completion
--> usbFlags
Should be set to 0

In order to avoid the loss of data when transferring data from a device, usbBuffer and usbReqCount should be a multiple of the value of the MaxPacketSize field, in the device's endpoint descriptor.

Errors returned by the USBIntRead function include

kUSBUnknownPipeErr -6997 pipe reference specified is unknown
kUSBIncorrectTypeErr -6995 pipe is not an interrupt pipes
kUSBPipeIdleErr -6980 specified pipe is in the idle state
kUSBPipeStalledErr -6979 specified pipe is stalled

USBBulkRead

The USBBulkRead function can be used to request multiple bulk transactions on an inbound bulk pipe to fulfill the size of request specified, or for the entire transfer.

OSStatus USBBulkRead(USBPB *pb);

Required fields in the USBPB parameter block for the USBBulkRead function are

--> pbLength
Length of parameter block
--> pbVersion
Parameter block version number
--> usbCompletion
The completion routine
--> usbRefcon
General-purpose value passed back to the completion routine
--> usbReference
The pipe reference returned by the USBFindNextPipe function
--> usbReqCount
Specifies the size of the data to transfer. Must be a multiple of the packet size. If it is not a multiple of the packet size, the last packet my overrun. If set to 0, any non-zero size transfer causes an error
--> usbBuffer
Points to a buffer to which the incoming data is transferred
<-- usbActCount
Specifies the actual amount of data transferred on completion
--> usbFlags
Should be set to 0

In order to avoid the loss of data when transferring data from a device, usbBuffer and usbReqCount should be a multiple of the endpoint MaxPacketSize in the device's endpoint descriptor.

Errors returned by the USBBulkRead function include

kUSBUnknownPipeErr -6997 pipe reference specified is unknown
kUSBIncorrectTypeErr -6995 pipe reference is not a bulk-in pipe
kUSBPipeIdleErr -6980 specified pipe is in the idle state
kUSBPipeStalledErr -6979 specified pipe is stalled

USBBulkWrite

The USBBulkWrite function requests multiple bulk out transactions on an outbound bulk pipe to fulfill the size of request specified.

OSStatus USBBulkWrite(USBPB *pb);

Required fields in the USBPB parameter block for the USBBulkWrite function are

--> pbLength
Length of parameter block
--> pbVersion
Parameter block version number
--> usbCompletion
The completion routine
--> usbRefcon
General-purpose value passed back to the completion routine
--> usbReference
The pipe reference returned by the USBFindNextPipe or USBOpenPipe functions
--> usbReqCount
Specifies the size of the data to transfer. If this is set to 0, no data transfer occurs, but the device senses a 0 length bulk transaction
--> usbBuffer
Points to the data to be transferred. The buffer should be at least as big as the size specified in the usbReqCount field. If the buffer is set to nil, no data is transferred regardless of the value of usbReqCount
<-- usbActCount
Specifies the actual amount of data transferred on completion
--> usbFlags
Should be set to 0
Errors returned by the USBBulkWrite function include
kUSBUnknownPipeErr -6997 pipe reference specified is unknown
kUSBIncorrectTypeErr -6995 pipe reference is not a bulk-out pipe
kUSBPipeIdleErr -6980 specified pipe is in the idle state
kUSBPipeStalledErr -6979 specified pipe is stalled

USBIsocRead

The USBIsocRead function is defined as follows:

OSStatus USBIsocRead(USBIsocPB *pb);

Required fields in the isochronous version of the USBPB parameter block for the USBIsocRead function are

--> pbLength
Length of parameter block
--> pbVersion
Parameter block version, must be kUSBIsocPBVersion for isochronous function calls
<--usbStatus
Aggregate status, see discussion in The Isochronous Version Of The USBPB
--> usbCompletion
The completion routine
--> usbRefcon
General-purpose value passed back to the completion routine
--> usbReference
The isochronous pipe reference returned by the USBFindNextPipe function
--> usbReqCount
Specifies the size of the data to transfer. May be any size, but no less than the sum of the individual packets sizes. If set to 0, any non-zero size transfer causes an error.
--> usbBuffer
Points to a buffer to which the incoming data is transferred
<-- usbActCount
Specifies the actual amount of data transferred on completion
--> usbFlags
Should be set to 0
--> usb.isoc.FrameList
Pointer to the list of frame structures --> frReqCount Number of bytes requested for each packet <-- frStatus Status returned by packet <-- frActCount Actual bytes transferred by packet
--> usb.isoc.NumFrames
Number of frames to attempt transfers in
--> usbFrame
Frame number of the first frame to transfer data

USBIsocWrite

The USBIsocWrite function is defined asfollows:

USBIsocWrite(USBIsocPB *pb);

Required fields in the isochronous version of the USBPB parameter block for the USBIsocWrite function are

--> pbLength
Length of parameter block
--> pbVersion
Parameter block version, must be kUSBIsocPBVersion for isochronous function calls
<--usbStatus
Aggregate status, see discussion in The Isochronous Version Of The USBPB
--> usbCompletion
The completion routine
--> usbRefcon
General-purpose value passed back to the completion routine
--> usbReference
The isochronous pipe reference returned by the USBFindNextPipe or USBOpenPipe functions
--> usbReqCount
Specifies the size of the data to transfer. If this is set to 0 in the frReqCount field in the frame structure, the call sends a packet size of 0.
--> usbBuffer
Points to the data to be transferred. The buffer should be at least as big as the size specified in the usbReqCount field. If the buffer is set to nil, no data is transferred regardless of the value of usbReqCount
<-- usbActCount
Specifies the actual amount of data transferred on completion
--> usbFlags
Should be set to 0
--> usb.isoc.FrameList
Pointer to the list of frame structures --> frReqCount Number of bytes requested for each packet <-- frStatus Status returned by packet <-- frActCount Actual bytes transferred by packet
--> usb.isoc.NumFrames
Number of frames to attempt transfers in
--> usbFrame
Frame number of the first frame to transfer data

© 1998 Apple Computer, Inc. – (Last Updated 23 Nov 98)

Previous | Back Up One Level | Next |